
\section{About Options: Preliminaries}

\PGFPlots{} knows a whole lot of key--value options which can be (re)defined to
activate desired features or modified to apply some fine-tuning.

A key usually has a value (like a number, a string, or perhaps some macro
code). You can assign values to keys (``set keys'') in many places in a
\LaTeX{} document. The value will remain effective until it is changed or until
the current \TeX{} scope ends (which happens after a closing curly brace `|}|',
after |\end|\marg{name} or, for example, after |\addplot|).

\noindent Most keys can be used like
%
\begin{codeexample}[code only]
\begin{tikzpicture}
\begin{axis}[key=value,key2=value2] % axis-wide keys
...
\end{axis}
\end{tikzpicture}
\end{codeexample}
%
\noindent which changes them for the complete axis. A |key| in this context can
be any option defined in this manual, no matter if it has the |/pgfplots/| or
the |/tikz/| key prefix. Note that key prefixes can be omitted in almost all
cases.

A value can usually be provided without curly braces. For example, if the
manual contains something like `|xmin=|\marg{$x$-coordinate}', you can safely
skip the curly braces. The curly braces are mandatory if values contain
something which would otherwise confuse the key setup (for example an equal
sign `|=|' or a comma `|,|').

Some keys can be changed individually for each plot:
%
\begin{codeexample}[code only]
\begin{tikzpicture}
    \begin{axis}
        % keys valid for single plots:
        \addplot ... ;                          % uses the "cycle list" to determine keys
        \addplot [key=value,key2=value2] ... ;  % uses the provided keys (not the "cycle list")
        \addplot+ [key=value,key2=value2] ... ; % appends something to the "cycle list"
    \end{axis}
\end{tikzpicture}
\end{codeexample}

Besides these two possibilities, it is also possible to work with document-wide
keys:
%
\begin{codeexample}[code only]
\chapter{My Chapter}
\pgfplotsset{
    key=value,
    key2=value2,
}
This chapter has a common key configuration:
\begin{tikzpicture}
    \begin{axis}% uses the key config from above
    ...
    \end{axis}
\end{tikzpicture}
\end{codeexample}
%
\noindent In the example above, the |\pgfplotsset| command changes keys. The
changes are permanent and will be used until
%
\begin{itemize}
    \item you redefine them or
    \item the current environment (like |\end{figure}|) is ended or
    \item \TeX{} encounters a closing brace `|}|'.
\end{itemize}
%
This includes document-wide preamble configurations like
%
\begin{codeexample}[code only]
\documentclass{article}

\usepackage{pgfplots}
\pgfplotsset{
    xticklabel={$\mathsf{\pgfmathprintnumber{\tick}}$},
    every axis/.append style={
        font=\sffamily,
    },
}
...
\end{codeexample}

The basic engine to manage key--value pairs is |pgfkeys| which is part of
\pgfname{}. This engine always has a key name and a key ``path'', which is
somehow similar to file name and directory of files. The common ``directory''
(key path) of \PGFPlots{} is `|/pgfplots/|'. Although the key definitions below
provide this full path, it is always (well, almost always) safe to skip this
prefix -- \PGFPlots{} uses it automatically. The same holds for the prefixes
`|/tikz/|' which are common for all \Tikz{} drawing options and `|/pgf/|' which
are for the (more or less) low-level commands of \pgfname{}. All these prefixes
can be omitted.

One important concept is the concept of \emph{styles}. A style is a key which
contains one or more other keys. It can be redefined or modified until it is
actually used by the internal routines. Each single component of \Tikz{} and
\PGFPlots{} can be configured with styles.

For example,
%
\begin{codeexample}[code only]
\pgfplotsset{legend style={line width=1pt}}
\end{codeexample}
%
\noindent sets the line width for every legend to |1pt| by appending
`|line width=1pt|' to the existing style for legends.

There are keys like |legend style|, |ticklabel style|, and |label style| which
allow to modify the predefined styles (in this case the styles for legends,
ticklabels and axis labels, respectively). They are, in general, equivalent to
a \meta{style name}|/.append style={}| command (the only difference is that the
|/.append style| thing is a little bit longer). There is also the possibility
to define a new style (or to overwrite an already existing one) using
|/.style={}|.

There are several other styles predefined to modify the appearance, see
Section~\ref{sec:styles}.

\begin{command}{\pgfplotsset\marg{key-value-list}}
    Defines or sets all options in \meta{key-value-list}. The
    \meta{key-value-list} can contain any of the options in this manual which
    have the prefix |/pgfplots/| (however, you do not need to type that
    prefix).

    Inside of \meta{key-value-list}, the prefixes `|/pgfplots/|' which are
    commonly presented in this manual can be omitted (they are checked
    automatically).

    This command can be used to define default options for the complete
    document or a part of the document. For example,
    %
\begin{codeexample}[code only]
\pgfplotsset{
    cycle list={
        {red, mark=*},          {blue,mark=*},
        {red, mark=x},          {blue,mark=x},
        {red, mark=square*},    {blue,mark=square*},
        {red, mark=triangle*},  {blue,mark=triangle*},
        {red, mark=diamond*},   {blue,mark=diamond*},
        {red, mark=pentagon*},  {blue,mark=pentagon*}
    },
    legend style={
        at={(0.5,-0.2)},
        anchor=north,
        legend columns=2,
        cells={anchor=west},
        font=\footnotesize,
        rounded corners=2pt,
    },
    xlabel=$x$,
    ylabel=$f(x)$,
}
\end{codeexample}
    %
    can be used to set document-wise styles for line specifications, the
    legends' style and axis labels. The settings remain in effect until the end
    of the current environment (like |\end{figure}|) or until you redefine them
    or until the next closing curly brace `|}|' (whatever comes first).

    You can also define new styles (collections of key--value pairs) with
    |/.style| and |/.append style|.
    %
\begin{codeexample}[code only]
\pgfplotsset{
    My Style 1/.style={xlabel=$x$, legend entries={1,2,3} },
    My Style 2/.style={xlabel=$X$, legend entries={4,5,6} }
}
\end{codeexample}
    %
    The |/.style| and |/.append style| key handlers are described in
    Section~\ref{sec:styles} in more detail.
\end{command}

\begin{handler}{{.code}=\marg{\TeX{} code}}
    Occasionally, the \PGFPlots{} user interface offers to replace parts of its
    routines. This is accomplished using so called ``code keys''. What it means
    is to replace the original key and its behavior with new \meta{\TeX{}
    code}. Inside of \meta{\TeX{} code}, any command can be used. Furthermore,
    the |#1| pattern will be the argument provided to the key.

\begin{codeexample}[]
\pgfplotsset{
    My Code/.code={I've been invoked with `#1'}}
\pgfplotsset{My Code={this here}}
\end{codeexample}
    %
    The example defines a (new) key named |My Code|. Essentially, it is nothing
    else but a |\newcommand|, plugged into the key--value interface. The second
    statement ``invokes'' the code key.
\end{handler}

\begin{handler}{{.code 2 args}=\marg{\TeX{} code}}
    As |/.code|, but this handler defines a key which accepts two arguments.
    When the so defined key is used, the two arguments are available as |#1|
    and |#2|.
\end{handler}

\begin{handler}{{.cd}}
    Each key has a fully qualified name with a (long) prefix, like
    |/pgfplots/xmin|. However, if the ``current directory'' is |/pgfplots|, it
    suffices to write just |xmin|. The |/.cd| key handler changes the ``current
    directory'' in this way.

    The prefixes |/tikz/| and |/pgfplots/| are checked automatically for any
    argument provided to |\begin{axis}|\oarg{options} or |\addplot|. So, you
    won't need to worry about them, just omit them -- and look closer in case
    the package doesn't identify the option.
\end{handler}


\subsection{\textsc{PGFPlots} and \Tikz{} Options}

This section is more or less technical and can be skipped unless one really
wants to know more about this topic.

\Tikz{} options and \PGFPlots{} options can be mixed inside of the axis
arguments and in any of the associated styles. For example,
%
\begin{codeexample}[code only]
\pgfplotsset{every axis legend/.append style={
    legend columns=3,font=\Large},
}
\end{codeexample}
%
\noindent assigns the `|legend columns|' option (a \PGFPlots{} option) and uses
`|font|' for drawing the legend (a \Tikz{} option). The point is:
|legend columns| needs to be known \emph{before} the legend is typeset whereas
|font| needs to be active when the legend is typeset. \PGFPlots{} sorts out any
key dependencies automatically:

The axis environments will process any known \PGFPlots{} options, and all
`|every|' styles will be parsed for \PGFPlots{} options. Every unknown option
is assumed to be a \Tikz{} option and will be forwarded to the associated
\Tikz{} drawing commands. For example, the `|font=\Large|' above will be used
as argument to the legend matrix, and the `|font=\Large|' argument in
%
\begin{codeexample}[code only]
\pgfplotsset{every axis label/.append style={
    ylabel=Error,xlabel=Dof,font=\Large},
}
\end{codeexample}
%
will be used in the nodes for axis labels (but not the axis title, for example).

It is an error if you assign incompatible options to axis labels, for example
`|xmin|' and `|xmax|' can't be set inside of `|every axis label|'.
